home *** CD-ROM | disk | FTP | other *** search
/ 8bitfiles.net/archives / archives.tar / archives / compuserve-file-archive / 09 Application Software / ACE-15E.SFX / ace15-as.doc next >
Text File  |  1995-12-17  |  49KB  |  991 lines
  1. ┴├┼ ┴SSEMBLER ─OCUMENTATION  FOR VERSION 1.20   [─ECEMBER 17, 1995]
  2. ------------------------------------------------------------------------------
  3. 1. ╔╬╘╥╧─╒├╘╔╧╬
  4.  
  5. ╘HE ┴├┼ ASSEMBLER IS A ONE-PASS ASSEMBLER.  ╘HE ONLY REAL LIMITATION ON THE
  6. SIZE OF ASSEMBLY JOBS IS THE AMOUNT OF NEAR+FAR MEMORY YOU HAVE AVAILABLE.
  7. ╠ABELS ARE "LIMITED" TO 240 CHARACTERS (ALL SIGNIFICANT), AND THE OBJECT
  8. SIZE IS LIMITED TO 64╦ (OF COURSE).  ╬UMERICAL VALUES ARE "LIMITED" TO
  9. 32-BITS OR LESS.  ╥ELATIVE LABELS ("+" AND "-" LABELS) ARE IMPLEMENTED IN
  10. THE SAME WAY AS IN THE ┬UDDY ASSEMBLER.  ┴DD, SUBTRACT, MULTIPLY, DIVIDE,
  11. MODULUS, AND, OR, AND XOR DYADIC OPERATORS ARE IMPLEMENTED FOR EXPRESSIONS
  12. WITH POSITIVE, NEGATE, HIGH-BYTE, AND LOW-BYTE MONADIC OPARATORS, AND THE
  13. PLANNED MACRO AND CONDITIONAL ASSEMBLY FEATURES ARE NOT YET IMPLEMENTED.
  14. ┼XPRESSIONS ARE LIMITED TO 17 OPERANDS (WITH 255 MONADIC OPERATORS EACH) AND
  15. ARE EVALUATES STRICTLY LEFT-TO-RIGHT, BUT REFERENCES TO UNRESOLVED
  16. IDENTIFIERS ARE ALLOWED ANYWHERE, INCLUDING EQUATE DEFINITIONS.
  17. ╚IERARCHICAL INCLUSION OF SOURCE FILES IS SUPPORTED, AND COMPATIBILITY
  18. FEATURES HAVE BEEN IMPLEMENTED TO ALLOW THIS ASSEMBLER TO ACCEPT DIRECTIVES
  19. AND SYNTAX OF OTHER ASSEMBLERS.  ┴LL OF THE ┴├┼ APPLICATIONS CAN BE
  20. ASSEMBLED USING THIS ASSEMBLER, INCLUDING THE ASSEMBLER ITSELF.
  21.  
  22. ╘HE ASSEMBLER IS DESIGNED TO BE A "HEAVY HITTER", OPERATES AT MODERATE
  23. SPEED, AND USES A FAIR AMOUNT OF DYNAMICALLY ALLOCATED MEMORY.  ╔N FACT, ON
  24. AN UNEXPANDED 64, YOU WON'T BE ABLE TO ASSEMBLE PROGRAMS THAT ARE TOO LARGE,
  25. INCLUDING THE ASSEMBLER ITSELF (89╦ OF SOURCE).  ┘OU'LL BE ABLE TO DO LARGER
  26. JOBS ON AN UNEXPANDED 64 IF YOU DEACTIVATE THE SOFT-80 SCREEN IN THE
  27. CONFIGURATION.  (╧F COURSE, ONE COULD ARGUE THAT ANY SERIOUS 64 HACKER WOULD
  28. HAVE EXPANDED MEMORY ANYWAYS...).
  29.  
  30. ╔N ADDITION TO THE REGULAR 6502 INSTRUCTIONS, THIS RELEASE OF THE ASSEMBLER
  31. HAS THE FOLLOWING DIRECTIVES:
  32.  
  33. LABEL = VALUE                ;ASSIGN GIVEN VALUE TO THE LABEL
  34. LABEL:                       ;ASSIGN THE CURRENT ASSEMBLY ADDRESS TO LABEL
  35. +                            ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS
  36. -                            ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS
  37. .ORG ADDRESS                 ;SET THE ORIGIN OF THE ASSEMBLY
  38. .BUF SIZE                    ;RESERVE "SIZE" BYTES OF SPACE,FILLED WITH ZEROES
  39. .INCLUDE "FILENAME"          ;SOURCE-FILE INCLUSION (NESTABLE)
  40. .BYTE VAL1, VAL2, ..., VAL╬  ;PUT BYTE VALUES INTO MEMORY
  41. .WORD VAL1, VAL2, ..., VAL╬  ;PUT WORD VALUES INTO MEMORY
  42. .TRIPLE VAL1, VAL2, ..., VAL╬ ;PUT "TRIPLE" (3-BYTE) VALUES INTO MEMORY, LO->HI
  43. .LONG VAL1, VAL2, ..., VAL╬  ;PUT "LONG" (4-BYTE) VALUES INTO MEMORY, LO->HI
  44.  
  45. ╘HESE FEATURES IS DESCRIBED IN MORE DETAIL BELOW.  ╬OTE THAT THROUGHOUT THE
  46. DOCUMENTATION, ╔ USE THE TERMS "IDENTIFIER", "SYMBOL", AND "LABEL"
  47. INTERCHANGEABLY.
  48.  
  49. ╘HE OFFICIAL NAME OF THE ASSEMBLER IS "THE ┴├┼ ASSEMBLER", BUT UNOFFICIALLY,
  50. IT CAN BE CALLED "┴├┼MBLER" TO GIVE IT A SPECIFIC ONE-WORD NAME.
  51. ------------------------------------------------------------------------------
  52. 2. ╒╙┴╟┼
  53.  
  54. ╘HE USAGE FOR THE AS COMMAND IS, STATED IN ╒NIX NOTATION:
  55.  
  56. USAGE: AS [-HELP] [-S] [-D] [-Q] [FILE ...]
  57.  
  58. ╘HE "-HELP" FLAG WILL CAUSE THE ASSEMBLER DISPLAY THE USAGE INFORMATION AND
  59. THEN EXIT, WITHOUT ASSEMBLING ANY CODE.  ┴CTUALLY, ANY FLAG THAT IT DOESN'T
  60. UNDERSTAND WILL BE TAKEN AS IF YOU HAD SAID "-HELP", BUT NOTE THAT IF YOU
  61. TYPE THE "AS" COMMAND ALONE ON A COMMAND LINE THAT USAGE INFORMATION WILL
  62. NOT BE GIVEN.
  63.  
  64. ╘HE "-S" FLAG TELLS THE ASSEMBLER TO GENERATE A SYMBOL-TABLE LISTING WHEN
  65. THE ASSEMBLY JOB IS FINISHED.  ╘HE TABLE IS FORMATTED FOR AN 80-COLUMN
  66. DISPLAY.  INDICATES THAT A SYMBOL TABLE SHOULD BE GENERATED WHEN THE
  67. ASSEMBLY JOB IS DONE.  ╘HE TABLE WILL LOOK LIKE:
  68.  
  69. ╘HE "-D" FLAG TELLS THE ASSEMBLER TO PRODUCE DEBUGGING INFORMATION WHILE IT
  70. IS WORKING.  ╔T WILL GENERATE A LOT OF OUTPUT, SO YOU CAN SEE EXACTLY WHAT
  71. IS GOING ON.
  72.  
  73. ╘HE "-Q" FLAG TELLS THE ASSEMBLER TO ACCEPT QUOTED TEXT (STRINGS) LITERALLY,
  74. WITHOUT PARSING BACKSLASH SEQUENCES INSIDE OF THE STRINGS.  ╘HIS FEATURE IS
  75. PROVIDED FOR COMPATIBILITY WITH SOURCE FILES FROM OTHER ASSEMBLERS.
  76.  
  77. ╘HE OBJECT-CODE MODULE NAME WILL BE "A.OUT" UNLESS THE NAME OF THE FIRST
  78. SOURCE FILE ENDS WITH A ".S" EXTENSION, IN WHICH CASE THE OBJECT MODULE WILL
  79. BE THE BASE NAME OF FIRST SOURCE FILE (WITHOUT THE EXTENSION).  ╘HE OBJECT
  80. MODULE WILL BE WRITTEN AS A ╨╥╟ FILE AND WILL BE IN ├OMMODORE-─╧╙ PROGRAM
  81. FORMAT: THE FIRST TWO BYTES WILL BE THE LOW AND HIGH BYTES OF THE CODE
  82. ADDRESS, AND THE REST WILL BE THE BINARY IMAGE OF THE ASSEMBLED CODE.
  83.  
  84. ╔F NO SOURCE FILENAME IS GIVEN ON THE COMMAND LINE, THEN INPUT IS TAKEN FROM
  85. THE STDIN FILE STREAM (AND WRITTEN TO "A.OUT").  ╔F MORE THAN ONE FILENAME
  86. IS GIVEN, THE EACH IS READ, IN TURN, INTO THE SAME ASSEMBLY JOB (AS IF THE
  87. FILES WERE "CAT"TED TOGETHER INTO ONE SOURCE FILE).  (╘HIS WILL CHANGE
  88. SUBTLY WHEN THE ASSEMBLER IS COMPLETED).
  89.  
  90. ╘HIS ASSEMBLER DOES NOT PRODUCE A LISTING OF THE CODE ASSEMBLED AND WILL
  91. STOP THE WHOLE ASSEMBLY JOB ON THE FIRST ERROR IT ENCOUNTERS.
  92. ------------------------------------------------------------------------------
  93. 3. ╘╧╦┼╬╙
  94.  
  95. ╫HILE READING YOUR SOURCE CODE, THE ASSEMBLER GROUPS CHARACTERS INTO TOKENS
  96. AND INTERPRETS THEM AS A COMPLETE UNIT.  ╘HE ASSEMBLER WORKS WITH FIVE
  97. DIFFERENT TYPES OF TOKENS: IDENTIFIERS, NUMERIC LITERALS, STRING LITERALS,
  98. SPECIAL CHARACTERS, AND END-OF-FILE (EOF).  ┼OF IS SPECIAL SINCE IT DOESN'T
  99. ACTUALLY INCLUDE ANY CHARACTERS, AND ITS ONLY MEANING IS TO STOP READING
  100. FROM THE CURRENT SOURCE.  ┘OUR INPUT SOURCE FILE SHOULD CONSIST ONLY OF
  101. CHARACTERS THAT ARE PRINTABLE IN STANDARD ┴╙├╔╔ (DON'T BE CONFUSED BY THIS;
  102. THE ASSEMBLER EXPECTS ITS INPUT TO BE IN ╨┼╘╙├╔╔) PLUS ╘┴┬ AND
  103. ├ARRIAGE-╥ETURN.  ╧THER CHARACTERS MAY CONFUSE THE ASSEMBLER.
  104.  
  105. ╔DENTIFIERS CONSIST OF A LOWERCASE OR UPPERCASE LETTER OR AN UNDERSCORE (_)
  106. FOLLOWED BY A SEQUENCE OF SUCH LETTERS OR DECIMAL DIGITS OR PERIODS (.).
  107. ╘HIS IS A PRETTY STANDARD DEFINITION OF AN IDENTIFIER.  ╔DENTIFIERS ARE
  108. LIMITED TO 240 CHARACTERS IN LENGTH AND AN ERROR WILL BE REPORTED IF YOU TRY
  109. TO USE ONE LONGER THAN THAT.  ┴LL OF THE CHARACTERS OF ALL IDENTIFIERS ARE
  110. SIGNIFICANT, AND LETTERS ARE CASE-SENSITIVE.  ╚ERE ARE SOME EXAMPLES OF
  111. ALL-UNIQUE IDENTIFIERS:
  112.  
  113. HELLO  ╚ELLO  _TIME4  A1_X140╩  ╚ELLO╘HERE╘HIS╔S┴_╠ONG╧NE
  114.  
  115. ╬UMERIC LITERALS COME IN THREE TYPES: DECIMAL, HEXADECIMAL, AND BINARY.
  116. ─ECIMAL LITERALS CONSIST OF AN INITIAL DIGIT FROM 0 TO 9 FOLLOWED BY ANY
  117. NUMBER OF DIGITS, PROVIDED THAT THE VALUE DOES NOT EXCEED 2^32-1 (APPROX. 4
  118. BILLION).  ┴LL TYPES OF LITERALS CAN ALSO HAVE EMBEDDED UNDERSCORE
  119. CHARACTERS, WHICH ARE IGNORED BY THE ASSEMBLER.  ╒SE THEM GROUPING DIGITS
  120. (LIKE THE COMMA FOR BIG ┴MERICAN NUMBERS).
  121.  
  122. ╚EXADECIMAL LITERALS CONSIST OF A DOLLAR SIGN ($) FOLLOWED BY ANY NUMBER OF
  123. HEXADECIMAL DIGITS, PROVIDED THE VALUE DOESN'T OVERFLOW 32 BITS.  ╚EXADECIMAL
  124. DIGITS INCLUDE THE DECIMAL DIGITS (0-9), AND THE FIRST SIX UPPERCASE OR
  125. LOWERCASE LETTERS OF THE ALPHABET (EITHER A-F OR ┴-╞).  ╚EXADECIMAL LITERALS
  126. CAN ALSO HAVE EMBEDDED UNDERSCORE CHARACTERS FOR SEPARATORS.
  127.  
  128. ┬INARY LITERALS CONSIST OF A PERCENT SIGN (%) FOLLOWED BY ANY NUMBER OF
  129. BINARY DIGITS THAT DON'T OVERFLOW 32-BITS VALUES.  ╘HE BINARY DIGITS ARE, OF
  130. COURSE, 0 AND 1, AND LITERALS MAY INCLUDE EMBEDDED UNDERSCORE CHARACTERS.
  131. ╬OTE THAT NEGATIVE VALUES ARE NOT LITERALS.  ╚ERE ARE SOME EXAMPLES OF VALID
  132. LITERALS:
  133.  
  134. 0  123  0001  4_294_967_295  $AE╞╞  $0123_4567  %010100 %110_1010_0111_1010
  135.  
  136. ╙TRING LITERALS ARE SEQUENCES OF CHARACTERS ENCLOSED IN EITHER SINGLE (') OR
  137. DOUBLE (") QUOTATION MARKS.  ╘HE ENCLOSED CHARACTERS ARE NOT INTERPRETED TO
  138. BE INDEPENDENT TOKENS, NOMATTER WHAT THEY ARE.  ╧NE EXCEPTION IS THAT THE
  139. CARRIAGE-RETURN CHARACTER CANNOT BE ENCLOSED IN A STRING (THIS NORMALLY
  140. INDICATES AN ERROR ANYWAY).  ╘O GET SPECIAL NON-PRINTABLE CHARACTERS INTO
  141. YOUR STRINGS, AN "ESCAPE" CHARACTER IS PROVIDED: THE BACKSLASH (\).  ╔F THE
  142. BACKSLASH CHARACTER IS ENCOUNTERED, THEN THE CHARACTER FOLLOWING IT IS
  143. INTERPRETED AND A SPECIAL CHARACTER CODE IS PUT INTO THE STRING IN PLACE OF
  144. THE BACKSLASH AND THE FOLLOWING CHARACTER.  ╚ERE ARE THE CHARACTERS ALLOWED
  145. TO FOLLOW A BACKSLASH:
  146.  
  147. ├╚┴╥   ├╧─┼   ═┼┴╬╔╬╟
  148. ----   ----   --------
  149. \        92   BACKSLASH CHARACTER (\)
  150. N        13   CARRIAGE RETURN (NEWLINE)
  151. B        20   BACKSPACE (THIS IS A NON-DESTRUCTIVE BACKSPACE FOR ┴├┼)
  152. T         9   TAB
  153. R        10   GOTO BEGINNING OF LINE (FOR ┴├┼, LINEFEED FOR ├┬═)
  154. A         7   BELL SOUND
  155. Z         0   NULL CHARACTER (OFTEN USED AS A STRING TERMINATOR IN ┴├┼)
  156. 0         0   NULL CHARACTER
  157. '        39   SINGLE QUOTE (')
  158. E        27   ESCAPE
  159. Q        34   QUOTATION MARK
  160. "        34   QUOTATION MARK
  161.  
  162. ╙O, IF YOU REALLY WANT A BACKSLASH THEN YOU HAVE TO USE TWO OF THEM.  ╔F YOU
  163. WISH TO INCLUDE AN ARBITRARY CHARACTER IN A LITERAL STRING, NO FACILITY IS
  164. PROVIDED FOR DOING THAT.  ╚OWEVER, THE ASSEMBLER WILL ALLOW YOU TO INTERMIX
  165. STRINGS AND NUMERIC EXPRESSIONS AT A HIGHER LEVEL, SO YOU CAN DO IT THAT
  166. WAY.  ╙TRINGS ARE LIMITED TO INCLUDE 240 (ENCODED) CHARACTERS OR LESS.  ╘HIS
  167. IS REALLY NO LIMITATION TO ASSEMBLING, SINCE YOU CAN PUT AS MANY STRING
  168. LITERALS CONTIGUOUSLY INTO MEMORY AS YOU WISH.  ╚ERE ARE SOME EXAMPLES:
  169.  
  170. "╚ELLO THERE"  "ERROR!\A\A"  'FILE "OUTPUT" COULD NOT BE OPENED\N\0'
  171. "YOU 'DUMMY'!"  'YOU \'DUMMY\'!'  "╚ERE ARE TWO BACKSLASHES: \\\\"
  172.  
  173. ╙PECIAL CHARACTERS ARE SINGLE CHARACTERS THAT CANNOT BE INTERPRETED AS ANY
  174. OF THE OTHER TYPES OF TOKENS.  ╘HESE ARE USUALLY "PUNCTUATION" CHARACTERS,
  175. BUT CARRIAGE RETURN IS ALSO A SPECIAL-CHARACTER TOKEN (IT IS A STATEMENT
  176. SEPARATOR).  ╙OME EXAMPLES FOLLOW:
  177.  
  178. ,  (  #  &  )  =  /  ?  \  ▐  █  
  179.  
  180. ╘OKENS ARE SEPARATED BY EITHER THE NEXT CHARACTER OF INPUT NOT BEING ALLOWED
  181. TO BELONG TO THE CURRENT TOKEN TYPE, OR ARE SEPARATED BY WHITESPACE.
  182. ╫HITESPACE CHARACTERS INCLUDE ╙╨┴├┼ (" ") AND ╘┴┬.  ╬OTE THAT CARRIAGE
  183. RETURN IS NOT COUNTED AS WHITESPACE.  ├OMMENTS ARE ALLOWED BY USING A ";"
  184. CHARACTER.  ┼VERYTHING FOLLOWING THE SEMICOLON UP TO BUT NOT INCLUDING THE
  185. CARRIAGE RETURN AT THE END OF THE LINE WILL BE IGNORED BY THE ASSEMBLER.  (╔
  186. MAY IMPLEMENT AN ARTIFICAL-INTELLIGENCE COMMENT PARSER TO MAKE SURE THE
  187. ASSEMBLER DOES WHAT YOU WANT IT TO, BUT THIS WILL BE STRICTLY AN OPTIONAL,
  188. TIME-PERMITTING FEATURE).
  189. ------------------------------------------------------------------------------
  190. 4. ┼╪╨╥┼╙╙╔╧╬╙
  191.  
  192. ╬UMERIC EXPRESSIONS CONSIST OF OPERANDS AND OPERATORS.  ╔F YOU DON'T KNOW
  193. WHAT OPERANDS AND OPERATORS ARE, THEN GO BUY AN ELEMENTARY-SCHOOL MATH
  194. BOOK.  ╘HERE ARE SIX TYPES OF OPERANDS: NUMERIC LITERALS, SINGLE-CHARACTER
  195. STRING LITERALS, IDENTIFIERS, THE ASTERISK CHARACTER, ONE OR MORE PLUS
  196. SIGNS, AND ONE OR MORE MINUS SIGNS.  ╘HESE LAST THREE TYPES CAN MAKE PARSING
  197. AN EXPRESSION A BIT CONFUSING, BUT THEY ARE NECESSARY AND USEFUL.
  198.  
  199. ╬UMERIC LITERALS ARE PRETTY EASY TO THINK ABOUT.  ╘HEY'RE JUST 32-BIT
  200. NUMBERS AND WORK IN THE USUAL WAY.  ╙INGLE-CHARACTER STRING LITERALS ARE
  201. ALSO INTERPRETED (IN THE CONTEXT OF A NUMERIC EXPRESSION) AS BEING A NUMERIC
  202. LITERAL.  ╘HE VALUE OF A SINGLE-CHARACTER STRING IS SIMPLY THE ╨┼╘╙├╔╔ CODE
  203. FOR THE CHARACTER.
  204.  
  205. ╔DENTIFIERS OR "SYMBOLS" OR "LABELS" USED IN EXPRESSIONS REFER TO NUMERIC
  206. VALUES THAT HAVE BEEN OR WILL BE ASSIGNED TO THE IDENTIFIERS.  ┬INDING
  207. VALUES TO IDENTIFIERS IS DONE BY ASSEMBLER DIRECTIVES DISCUSSED IN A LATER
  208. SECTION.  ╔F AN IDENTIFIER ALREADY HAS A VALUE ASSIGNED TO IT BY THE TIME
  209. THAT THE CURRENT EXPRESSION IS REACHED IN ASSEMBLY, THEN IT IS TREATED AS IF
  210. IT WERE A NUMERIC LITERAL OF THE VALUE ASSIGNED TO THE IDENTIFIER.  ╔F THE
  211. IDENTIFIER CURRENTLY HAS NO VALUE ASSIGNED TO IT (I.E., IT IS "UNRESOLVED"),
  212. THEN THE ENTIRE CURRENT EXPRESSION WILL BE UNRESOLVED.  ╔N THIS CASE, THE
  213. VALUE OF THE EXPRESSION WILL BE RECORDED AND WILL BE EVALUATED AT A LATER
  214. TIME WHEN ALL OF ITS IDENTIFIERS BECOME RESOLVED.  ┴ "HOLE" WILL BE CREATED
  215. WHERE THE EXPRESSION SHOULD GO, AND THE HOLE WILL BE "FILLED IN" LATER.
  216. ╬OTE THAT THERE ARE A COUPLE OF DIRECTIVES FOR WHICH AN EXPRESSION MUST BE
  217. RESOLVED AT THE TIME IT IS REFERENCED.
  218.  
  219. ╘HE ASTERISK CHARACTER OPERATES MUCH LIKE A NUMERIC LITERAL, EXCEPT THAT ITS
  220. VALUE IS THE CURRENT CODE ADDRESS RATHER THAN A CONSTANT.  ╘HE CURRENT CODE
  221. ADDRESS WILL ALWAYS BE FOR THE START OF AN ASSEMBLER INSTRUCTION.  ╔.E., THE
  222. CURRENT CODE ADDRESS IS INCREMENTED ONLY AFTER AN INSTRUCTION IS ASSEMBLED.
  223. ╘HIS HAS SOME SUBTLE IMPLICATIONS, AND OTHER ASSEMBLERS MAY IMPLEMENT
  224. SLIGHTLY DIFFERENT SEMANTICS.  ─IRECTIVES ARE A LITTLE DIFFERENT IN THAT THE
  225. ADDRESS IS INCREMENTED AFTER EVERY VALUE IN A "COMMALIST" IS PUT INTO
  226. MEMORY.
  227.  
  228. ╥ELATIVE REFERENCES, I.E., OPERANDS CONSISTING OF A NUMBER OF PLUSES OR
  229. MINUSES, OPERATE MUCH LIKE IDENTIFIERS.  ╘HEY ARE PROVIDED FOR CONVENIENCE
  230. AND WORK EXACTLY HOW THEY DO IN THE ┬UDDY ASSEMBLER.  ╧PERANDS OF ALL
  231. MINUSES ARE BACKWARD REFERENCES AND OPERANDS OF ALL PLUSES ARE FORWARD
  232. REFERENCES.  ┬ECAUSE OF PARSING DIFFICULTIES, RELATIVE-REFERENCE OPERANDS
  233. MUST EITHER BE THE LAST OPERAND IN AN EXPRESSION OR MUST BE FOLLOWED BY A
  234. ":" CHARACTER.
  235.  
  236. ╘HE NUMBER OF PLUSES OR MINUSES TELL WHICH RELATIVE REFERENCE "POINT" IS
  237. BEING REFERRED TO.  ┴ REFERENCE POINT IS SET BY THE "+" AND "-" ASSEMBLER
  238. DIRECTIVES DISCUSSED LATER.  ╘HIS GETS DIFFICULT TO EXPLAIN WITH WORDS, SO
  239. HERE IS A CODE EXAMPLE:
  240.  
  241.    LDY #5
  242. -  LDX #0
  243. -  LDA NAME1,X
  244.    STA NAME2,X
  245.    BEQ +
  246.    CMP #"X"
  247.    BEQ ++
  248.    INX
  249.    BNE -
  250. +  DEY
  251.    BNE --
  252. +  RTS
  253.  
  254. ╘HIS RELATIVELY BOGUS SUBROUTINE WILL COPY A NULL-TERMINATED CHARACTER
  255. STRING FROM NAME1 TO NAME2 FIVE TIMES, UNLESS THE STRING CONTAINS AN "X"
  256. CHARACTER, IN WHICH CASE THE COPY OPERATION TERMINATES IMMEDIATELY UPON
  257. ENCOUNTERING THE "X".  ╘HE "BEQ +" BRANCHES TO THE NEXT "+" LABEL TO OCCUR
  258. IN THE CODE, TO THE "DEY" INSTRUCTION.  ╘HE "BEQ ++" BRANCHES TO THE "RTS",
  259. TO THE "+" LABEL FOLLOWING THE NEXT "+" LABEL ENCOUNTERED.  ╘HE "-" AND "--"
  260. REFERENCES WORK SIMILARLY, EXCEPT THAT THEY REFER TO THE PREVIOUS "-" LABEL
  261. AND THE PREVIOUS TO THE PREVIOUS "-" LABEL.  ┘OU CAN USE UP TO 255 PLUSES OR
  262. MINUS SIGNS IN A RELATIVE-REFERENCE OPERAND TO REFER TO THAT MANY REFERENCE
  263. POINTS AWAY.
  264.  
  265. ╘HAT ╔ SAID RELATIVE-REFERENCE OPERANDS WORK MUCH LIKE IDENTIFIERS ABOVE IS
  266. NO COOINCIDENCE.  ╞OR EACH DEFINITION OF A REFERENCE POINT AND REFERENCE TO
  267. A POINT, AN INTERNAL IDENTIFIER IS GENERATED THAT LOOKS LIKE "╠+123C" OR
  268. "╠-123C".  ╬OTE THAT YOU CAN'T DEFINE OR REFER TO THESE IDENTIFIERS
  269. YOURSELF.
  270.  
  271. ╘HERE ARE TWO TYPES OF OPERATORS THAT CAN BE USED IN EXPRESSIONS: MONADIC
  272. AND DIADIC OPERATORS.  ═ONADIC OPERATORS AFFECT ONE OPERAND, AND DYADIC
  273. OPERATORS AFFECT TWO OPERANDS.  ┴T ABOUT THIS POINT, ╔ SHOULD SPELL OUT THE
  274. ACTUAL FORM OF AN EXPRESSION.  ╔T IS:
  275.  
  276. [MONADIC_OPERATORS] OPERAND [ OPERATOR [MONADIC_OPERATORS] OPERAND [...] ]
  277.  
  278. OR:
  279.  
  280. 1 + 2
  281. -1 + -+-2 + 3
  282.  
  283. ┴N EXPRESSION MAY HAVE UP TO 17 OPERANDS.
  284.  
  285. ╘HE MONADIC (ONE-OPERAND) OPERATORS ARE: POSITIVE (+), NEGATIVE (-),
  286. LOW-BYTE (<), AND HIGH-BYTES (>).  ┘OU CAN HAVE UP TO 255 OF EACH OF THESE
  287. MONADIC OPERATORS FOR EACH OPERAND OF AN EXPRESSION.  ╨OSITIVE DOESN'T
  288. ACTUALLY DO ANYTHING.  ╬EGATIVE WILL RETURN THE 32-BIT 2'S COMPLEMENT OF THE
  289. OPERAND THAT IT IS ATTACHED TO.  ╠OW-BYTE WILL RETURN THE LOWEST EIGHT BITS
  290. OF THE OPERAND IT IS ATTACHED TO.  ╚IGH-BYTE WILL RETURN THE HIGH-ORDER
  291. 24-BITS OF THE 32-BIT OPERAND IT IS ATTACHED TO.  ┴LL EXPRESSIONS ARE
  292. EVALUATED IN FULL 32-BIT PRECISION.  ╬OTE THAT YOU CAN USE THE HIGH-BYTES
  293. OPERATOR MORE THAN ONCE TO EXTRACT EVEN HIGHER BYTE.  ╞OR EXAMPLE,
  294. "<>>VALUE" WILL EXTRACT THE SECOND-HIGHEST BYTE OF THE 32-BIT VALUE.
  295.  
  296. ╘HE DYADIC (TWO-OPERAND) OPERATORS THAT ARE IMPLEMENTED ARE: ADD (+),
  297. SUBTRACT (-), MULTIPLY (*), DIVIDE (/), MODULUS (!), BITWISE-AND (&),
  298. BITWISE-OR (▄), AND BITWISE-EXCLUSIVE-OR (^).  ┘ES, THE PLUS AND MINUS
  299. SYMBOLS ARE HORRIBLY OVERLOADED, AND THE USUAL ╬OT (MODADIC) OPERATOR ISN'T
  300. IMPLEMENTED, SINCE IT CAN BE SIMULATED WITH ╪OR, AND "NOT, WITH RESPECT TO
  301. WHAT?" BECOMES A PROBLEM SINCE EVALUATIONS ARE PERFORMED WITH A FULL
  302. 32-BITS.  ╫E SHOULD ALREADY KNOW WHAT ALL OF THE IMPLEMENTED OPERATORS DO,
  303. EXCEPT MAYBE FOR ═ODULUS.  ╔T IS LIKE ─IVIDE, EXCEPT THAT ═ODULUS RETURNS
  304. THE ╥EMAINDER RATHER THAN THE ╤UOTIENT OF THE DIVISION RESULT.
  305.  
  306. ┼VALUATION OF DYADIC OPERATORS IS STRICTLY LEFT-TO-RIGHT, AND VALUE
  307. OVERFLOWS AND UNDERFLOWS ARE IGNORED.  ╓ALUES ARE ALWAYS CONSIDERED TO BE
  308. POSITIVE, BUT THIS DOESN'T IMPACT 2'S COMPLEMENT NEGATIVE ARITHMETIC FOR ADD
  309. AND SUBTRACT DYADIC OPERATORS.
  310.  
  311. ═ONADIC OPERATORS TAKE PRECEDENCE OVER DYADIC OPERATORS.  ┼VALUATION OF
  312. MONADIC OPERATORS IS DONE A LITTLE DIFFERENTLY.  ┴LL POSITIVE OPERATORS ARE
  313. THROWN OUT SINCE THEY DON'T ACTUALLY DO ANYTHING.  ╘HEN, IF THERE IS AN EVEN
  314. NUMBER OF NEGATIVE OPERATORS, THEY ARE THROWN OUT.  ╔F THERE IS AN ODD
  315. NUMBER OF NEGATIVE OPERATORS, THEN THE 2'S COMPLEMENT NEGATIVE OF THE
  316. OPERAND IS RETURNED.  ╘HEN, IF THERE ARE ANY HIGH-BYTES OPERATORS, THE VALUE
  317. IS SHIFTED THAT NUMBER OF BYTES TO THE RIGHT AND THE HIGHEST-ORDER BYTE OF
  318. THE VALUE IS SET TO ZERO ON EACH SHIFT.  ╬OTE THAT IT REALLY DOESN'T MAKE
  319. ANY SENSE TO PERFORM ANY MORE THAN THREE HIGH-BYTES OPERATORS.  ╘HEN, THE
  320. LOW-BYTE OPERATOR IS PREFORMED, IF ASKED FOR.  ╔T IS EQUIVALENT TO TAKING
  321. ANDING THE VALUE WITH $000000FF.  ╔T REALLY DOESN'T MAKE MUCH SENSE TO
  322. PERFORM THIS OPERATOR MORE THAN ONCE.  ┴LSO, IT DOESN'T MAKE ANY DIFFERENCE
  323. IN WHICH ORDER YOU PLACE THE MONADIC OPERATORS IN AN EXPRESSION; THEY ARE
  324. ALWAYS EVALUATED IN THE STATIC ORDER GIVEN ABOVE.
  325.  
  326. ╘HERE IS ONE EXCEPTION HERE.  ╔F THE FIRST OPERAND OF AN EXPRESSION HAS
  327. HIGH-BYTES AND/OR LOW-BYTE MONADIC OPERATORS, THEN THE REST OF THE
  328. EXPRESSION IS EVALUATED FIRST AND THEN THE HIGH/LOW-BYTE MONADIC OPERATORS
  329. ARE PERFORMED ON THE RESULT.  ╘HIS IS DONE TO BE CONSISTENT WITH OTHER
  330. ASSEMBLERS AND WITH USER EXPECTATIONS.
  331.  
  332. ╨ARENTHESES ARE NOT SUPPORTED.  ╚ERE ARE SOME EXAMPLES OF VALID EXPRESSIONS:
  333.  
  334. 2
  335. +2+1
  336. 2+-1
  337. 2+-------------------------------------1
  338. ++++:-+++:+---
  339. 1+"X"-"A"+"┴"
  340. <>>>4_000_000_000
  341. <LABEL+1
  342. >LABEL+1
  343. -1
  344.  
  345. ╘HIS LAST ONE ENDS UP WITH A VALUE OF NEGATIVE ONE, WHICH IS INTERPRETED AS
  346. REALLY BEING 4_294_967_295.  ╔F YOU WERE TO TRY AND DO SOMETHING LIKE
  347. "LDA #-1", YOU WOULD GET AN ERROR BECAUSE THE VALUE WOULD BE INTERPRETED AS
  348. BEING WAY TOO BIG.
  349.  
  350. ┼XPRESSIONS RESULTS AND IDENTIFIERS HAVE A DATA TYPE ASSOCIATED WITH THEM.
  351. ╘HERE ARE FOUR DATA TYPES: ╓ALUE, ┴DDRESS, ╠OW-BYTE, ╚IGH-BYTE. AND
  352. ╟ARBAGE.  ╘HE TYPE OF AN EXPRESSION IS RECORDED SINCE IT WILL BE REQUIRED TO
  353. PROVIDE OBJECT-MODULE RELOCATION FEATURES IN THE FUTURE.  ╓ALUES ARE WHAT
  354. YOU WOULD EXPECT AND COME FROM NUMERIC AND SINGLE-CHARACTER-STRING-LITERAL
  355. OPERANDS.  ╘HE ┴DDRESS TYPE COMES FROM THE ASTERISK AND RELATIVE REFERENCE
  356. OPERANDS AND FROM IDENTIFIER OPERANDS WHICH ARE DEFINED TO BE ADDRESSES.  ┴N
  357. ADDRESS IS DEFINED TO BE ONLY AN ADDRESS IN THE RANGE OF THE ASSEMBLED
  358. CODE.  ┴DDRESSES OUTSIDE OF THIS RANGE ARE CONSIDERED TO BE VALUES.  ╘HE
  359. ╚IGH-BYTE TYPE RESULTS FROM APPLYING THE HIGH-BYTES (>) OPERATOR TO AN
  360. ADDRESS OPERAND, AND THE ╠OW-BYTE TYPE, FROM APPLYING THE LOW-BYTE (<)
  361. OPERATOR.  ╘HE ╟ARBAGE TYPE RESULTS FROM USING AN OPERATOR ON TWO OPERANDS
  362. OF TYPES THAT DON'T MAKE ANY SENSE (FOR EXAMPLE, FROM MULTIPLYING ONE
  363. ┴DDRESS BY ANOTHER).  ╘HE RESULT-TYPE RULES FOR THE OPERATORS IS A BIT
  364. COMPLICATED, BUT IS INTUITIVE.  ┘OU DON'T HAVE TO WORRY ABOUT THEM SINCE THE
  365. ASSEMBLER TAKES CARE OF THEM AUTOMATICALLY.  ╦EEPING TRACK OF EXPRESSION
  366. TYPES MAKES IT POSSIBLE TO GENERATE A LIST OF ALL VALUES IN MEMORY THAT MUST
  367. BE MODIFIED IN ORDER TO RELOCATE A PROGRAM TO A NEW ADDRESS WITHOUT
  368. REASSEMBLING IT.
  369.  
  370. ╙TRING "EXPRESSIONS" CONSIST OF ONLY A SINGLE STRING LITERAL.  ╬O OPERATORS
  371. ARE ALLOWED.  ╙OME ASSEMBLER DIRECTIVES ACCEPT EITHER NUMERIC OR STRING
  372. EXPRESSIONS AND INTERPRET THEM APPROPRIATELY (LIKE "BYTE").
  373. ------------------------------------------------------------------------------
  374. 5. ╨╥╧├┼╙╙╧╥ ╔╬╙╘╥╒├╘╔╧╬╙
  375.  
  376. ╘HIS ASSEMBLER ACCEPTS THE 56 STANDARD 6502 PROCESSOR INSTRUCTIONS.  ╔T DOES
  377. NOT PROVIDE UN-DOCUMENTED 6502 INSTRUCTIONS NOR 65C02 NOR 65816 INSTRUCTIONS
  378. NOR CUSTOM PSEUDO-OPS.  ╘HE LATTER WILL BE PROVIDED BY FUTURE MACRO
  379. FEATURES.  ┴LL OF THE ASSEMBLER INSTRUCTIONS MUST BE IN LOWERCASE OR THEY
  380. WILL NOT BE RECOGNIZED.  ╚ERE ARE THE INSTRUCTIONS:
  381.  
  382. ╬╒═  ╔╬╙      ╬╒═  ╔╬╙      ╬╒═  ╔╬╙      ╬╒═  ╔╬╙      ╬╒═  ╔╬╙
  383. ---  ---      12.  BVC      24.  EOR      36.  PHA      48.  STA
  384. 01.  ADC      13.  BVS      25.  INC      37.  PHP      49.  STX
  385. 02.  AND      14.  CLC      26.  INX      38.  PLA      50.  STY
  386. 03.  ASL      15.  CLD      27.  INY      39.  PLP      51.  TAX
  387. 04.  BCC      16.  CLI      28.  JMP      40.  ROL      52.  TAY
  388. 05.  BCS      17.  CLV      29.  JSR      41.  ROR      53.  TSX
  389. 06.  BEQ      18.  CMP      30.  LDA      42.  RTI      54.  TXA
  390. 07.  BIT      19.  CPX      31.  LDX      43.  RTS      55.  TXS
  391. 08.  BMI      20.  CPY      32.  LDY      44.  SBC      56.  TYA
  392. 09.  BNE      21.  DEC      33.  LSR      45.  SEC
  393. 10.  BPL      22.  DEX      34.  NOP      46.  SED
  394. 11.  BRK      23.  DEY      35.  ORA      47.  SEI
  395.  
  396. ╘HE ASSEMBLER ALSO SUPPORTS 12 ADDRESSING MODES.  ╘HE "ACCUMULATOR"
  397. ADDRESSING MODE THAT CAN BE USED WITH THE ROTATE AND SHIFT INSTRUCTIONS IS
  398. TREATED LIKE THE IMMEDIATE ADDRESSING MODE, SO A SHIFT-LEFT-ACCUMULATOR
  399. INSTRUCTION WOULD BE JUST "ASL" RATHER THAN "ASL A".  ═ANY OTHER ASSEMBLERS
  400. GET RID OF THE ACCUMULATOR ADDRESSING MODE ALSO.  ╨ROCESSOR INSTRUCTIONS
  401. (AND ADDRESSING MODES WITH "X" AND "Y" IN THEM) MAY BE GIVEN IN EITHER
  402. UPPERCASE OR LOWERCASE, TO ALLOW FOR MAXIMUM COMPATIBILITY WITH SOURCE CODE
  403. FROM OTHER ASSEMBLERS.
  404.  
  405. ╚ERE IS THE TOKEN SYNTAX FOR THE ADDRESSING MODES (├╥ MEANS CARRIAGE
  406. RETURN):
  407.  
  408. NUM  NAME       GEN  BYT  EXAMPLE   TOKENS
  409. ---  ---------  ---  ---  -------   -------
  410. 01.  IMPLIED    00.    1            ├╥
  411. 02.  IMMEDIATE  00.    2  #123      #     / EXP8  / ├╥
  412. 03.  RELATIVE   00.    2  *+20      EXP16 / ├╥
  413. 04.  ZEROPAGE   07.    2  123       EXP8  / ├╥
  414. 05.  ZP,X       08.    2  123,X     EXP8  / ,     / X   / ├╥
  415. 06.  ZP,Y       09.    2  123,Y     EXP8  / ,     / Y   / ├╥
  416. 07.  ABSOLUTE   00.    3  12345     EXP16 / ├╥
  417. 08.  ABS,X      00.    3  12345,X   EXP16 / ,     / X   / ├╥
  418. 09.  ABS,Y      00.    3  12345,Y   EXP16 / ,     / Y   / ├╥
  419. 10.  INDIRECT   00.    3  (12345)   (     / EXP16 / )   / ├╥
  420. 11.  (IND,X)    00.    2  (123,X)   (     / EXP8  / ,   / X   / )  / ├╥
  421. 12.  (IND),Y    00.    2  (123),Y   (     / EXP8  / )   / ,   / Y  / ├╥
  422.  
  423. ┼ACH INSTRUCTION TAKES A COMPLETE LINE AND EACH ADDRESSING MODE MUST BE
  424. TERMINATED BY A CARRIAGE RETURN TOKEN (COMMENTS ARE SKIPPED).  ╘HE FORMAT OF
  425. AN INSTRUCTION LINE IS AS FOLLOWS:
  426.  
  427. [PREFIX_DIRECTIVES] INSTRUCTION ADDRESS_MODE_OPERAND
  428.  
  429. ╔N THE CASE THAT AN EXPRESSION IN AN ADDRESSING MODE IS RESOLVED AT THE
  430. POINT IT IS ENCOUNTERED AND ITS VALUE IS LESS THAN 256, THE ASSEMBLER WILL
  431. TRY TO USE THE ZERO-PAGE ADDRESSING MODES IF POSSIBLE.  ╧N THE OTHER HAND,
  432. IF A ZERO-PAGE ADDRESSING MODE IS UNAVAILABLE FOR AN INSTRUCTION, THEN THE
  433. ASSEMBLER WILL PROMOTE OR GENERALIZE THE ZERO-PAGE ADDRESSING MODE TO AN
  434. ABSOLUTE ADDRESSING MODE, IF POSSIBLE.  ╘HIS IS WHAT THE "GEN" COLUMN IN THE
  435. TABLE ABOVE SHOWS.  ╔F AFTER ATTEMPTING TO GENERALIZE THE ADDRESSING MODE
  436. THE GIVEN ADDRESSING MODE STILL NOT VALID WITH THE GIVEN INSTRUCTION, THEN
  437. AN ERROR WILL BE GENERATED.
  438.  
  439. ╔N THE CASE THAT AN EXPRESSION IN AN ADDRESSING MODE CANNOT BE RESOLVED AT
  440. THE POINT WHERE IT IS ENCOUNTERED IN THE ASSEMBLER'S SINGLE PASS, A HOLE IS
  441. LEFT BEHIND, AND THAT HOLE IS MADE AS "LARGE" AS POSSIBLE; IT IS ASSUMED
  442. THAT YOU WILL FILL IN THE HOLE WITH THE LARGEST VALUE POSSIBLE.  ╘HIS MEANS,
  443. FOR EXAMPLE, IF YOU WERE TO ASSEMBLE THE FOLLOWING INSTRUCTION:
  444.  
  445. LDA VAR,X
  446.  
  447. THEN THE ASSEMBLER WOULD ASSUME THIS IS AN ABSOLUTE MODE, AND WILL FILL IN
  448. THE HOLE LATER AS SUCH, EVEN IF IT TURNS OUT THAT "VAR" IS ASSIGNED A VALUE
  449. LESS THAN 256 LATER ON.  ╘HIS RESULTS IN SLIGHT INEFFICIENCY IN THE CODE
  450. PRODUCED BY THIS ASSEMBLER, BUT IT CAUSES MOST TWO-PASS ASSEMBLERS TO FAIL
  451. COMPLETELY ON A "PHASE ERROR".  ┴N EASY WAY TO AVOID THIS CIRCUMSTANCE IS TO
  452. MAKE SURE THAT ALL ZERO-PAGE LABELS ARE DEFINED BEFORE THEY ARE REFERRED
  453. TO.
  454.  
  455. ╘HE ADDRESSING MODES THAT REQUIRE A SINGLE BYTE VALUE AND THAT WILL NOT
  456. "GENERALIZE" TO AN ABSOLUTE MODE WILL HAVE A SINGLE-BYTE HOLE CREATED FOR
  457. THEM.  ╧NLY THE BRANCHING INSTRUCTIONS WILL BE INTERPRETED AS HAVING THE
  458. RELATIVE ADDRESSING MODE, AND A SINGLE-BYTE HOLE WILL BE LEFT.  ╘WO
  459. EXCEPTIONS TO THE ABOVE RULES ARE THE "STX ZP,Y" AND "STY ZP,X", WHICH WILL
  460. LEAVE A SINGLE-BYTE HOLE ON AN UNRESOLVED EXPRESSION, SINCE THE
  461. ABSOLUTE-MODE GENERALIZATIONS FOR THESE INSTRUCTIONS ARE NOT SUPPORTED BY
  462. THE PROCESSOR.
  463. ------------------------------------------------------------------------------
  464. 6. ─╔╥┼├╘╔╓┼╙
  465.  
  466. ╘HERE ARE CURRENTLY SIX CLASSES OF ASSEMBLER DIRECTIVES; THERE WILL BE
  467. MORE IN THE FUTURE.  ╞OR MAXIMUM COMPATIBILITY, ALL DIRECTIVES CAN BE
  468. IN EITHER UPPERCASE OR LOWERCASE.  ┴LSO, TO BE MORE STANDARD, MOST
  469. DIRECTIVES ARE REQUIRED TO START WITH THE DOT (.) CHARACTER.
  470.  
  471. 6.1. ─╧-╬╧╘╚╔╬╟ ─╔╥┼├╘╔╓┼╙
  472.  
  473. ╘HERE ARE THREE DO-NOTHING DIRECTIVES:
  474.  
  475. #                           ;DOES NOTHING
  476.                             ;BLANK LINE--DOES NOTHING
  477.  
  478. ┴ BLANK LINE IN YOUR SOURCE CODE WILL SIMPLY BE IGNORED.  ╘HIS HELPS TO MAKE
  479. CODE MUCH MORE READABLE.  ╘HE "#" DIRECTIVE IS A PREFIX DIRECTIVE.  ╘HIS
  480. MEANS THAT IT DOES NOT OCCUPY AN ENTIRE LINE BUT ALLOWS OTHER DIRECTIVES AND
  481. PROCESSOR INSTRUCTIONS TO FOLLOW IT ON THE SAME LINE (INCLUDING OTHER PREFIX
  482. DIRECTIVES).  (┬UT NOTE THAT YOU CAN FOLLOW ANY PREFIX DIRECTIVE BY THE
  483. BLANK-LINE DIRECTIVE, EFFECTIVELY ALLOWING PREFIX DIRECTIVES TO BE REGULAR
  484. FULL-LINE DIRECTIVES (POWERFUL COMBINING FORMS)).  ╘HE "#" DIRECTIVE IS
  485. SIMPLY IGNORED BY THE ASSEMBLER, BUT YOU CAN USE IT TO HIGHLIGHT CERTAIN
  486. LINES OF CODE OR OTHER DIRECTIVES.
  487.  
  488. 6.2. ┴╙╙╔╟╬═┼╬╘ ─╔╥┼├╘╔╓┼╙
  489.  
  490. ╘HERE ARE FOUR ASSIGNMENT DIRECTIVES.  ╘HEY ALL ASSIGN (BIND) A VALUE TO AN
  491. IDENTIFIER.  ╚ERE THEY ARE:
  492.  
  493. LABEL = EXPRESSION          ;ASSIGN GIVEN VALUE TO THE LABEL
  494. LABEL:                      ;ASSIGN THE CURRENT ASSEMBLY ADDRESS TO LABEL
  495. +                           ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS
  496. -                           ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS
  497.  
  498. ╘HE FIRST (LABEL=EXPR) IS THE MOST GENERAL.  ╔T ASSIGNS THE RESULT OF
  499. EVALUATING THE EXPRESSION TO THE GIVEN LABEL.  ┬ECAUSE THIS ASSEMBLER IS SO
  500. GOSH-DARNED AWESOME, THE EXPRESSION DOESN'T EVEN HAVE TO BE RESOLVED; A
  501. "HOLE" WILL BE CREATED SAYING TO FILL IN THE ASSIGNED LABEL WHEN ALL OF THE
  502. UNRESOLVED IDENTIFIERS IN THE EXPRESSION EVENTUALLY BECOME RESOLVED.  ═OST
  503. OTHER ASSEMBLERS (IN FACT, ALL THAT ╔ HAVE EVER HEARD OF) CAN'T DO THIS
  504. BECAUSE IT CAUSES UGLY IMPLEMENTATION PROBLEMS, LIKE CASCADING LABEL
  505. RESOLUTIONS.  ├ONSIDER THE FOLLOWING EXAMPLE:
  506.  
  507. LDA #A
  508. STA B,X
  509. A = B+3
  510. B = C-1
  511. C = 5
  512.  
  513. ┴T THE POINT WHERE C BECOMES DEFINED, THERE ARE NO "MEMORY HOLES" BUT THE
  514. LABEL HOLE "B" MUST BE EVALUATED AND FILLED IN.  "B" GETS ASSIGNED THE VALUE
  515. 4.  ┴T THIS POINT, THERE ARE TWO HOLES: THE ONE IN THE "STA" INSTRUCTION AND
  516. THE LABEL "A".  ╫E FILL THEM BOTH IN, ASSIGNING "A" THE VALUE 8, AND WE
  517. DISCOVER THAT WE NEED TO FILL IN A HEW HOLE: THE ONE IN THE "LDA"
  518. INSTRUCTION.  ╫E DO THAT AND WE ARE FINALLY DONE.  ╘HE IMPLEMENTATION CAN
  519. HANDLE ANY NUMBER OF THESE RECURSIVE LABEL HOLE-FILLINGS, LIMITED ONLY BY
  520. THE AMOUNT OF NEAR+FAR MEMORY YOU HAVE.
  521.  
  522. ┴ LABEL CAN ONLY BE ASSIGNED A VALUE ONLY ONCE, AND YOU WILL GET AN ERROR IF
  523. YOU TRY TO REDEFINE A LABEL, EVEN IF IT IS CURRENTLY UNRESOLVED.  ┴LSO, ALL
  524. EXRESSIONS MUST BE RESOLVED BY THE END OF THE ASSEMBLY JOB, OR AN ERROR WILL
  525. BE REPORTED (BUT ONLY ONE--NAMING THE FIRST UNRESOLVED LABEL THAT THE
  526. ASSEMBLER RUNS ACROSS; ╔ MAY FIX THIS UP IN THE FUTURE).
  527.  
  528. ╘HE SECOND ASSIGNMENT DIRECTIVE IS EQUIVALENT TO "LABEL = *", BUT IT IS MORE
  529. CONVENIENT AND IS ALSO A PREFIX DIRECTIVE.  ╔T ASSIGNS THE CURRENT ADDRESS
  530. (AS OF THE START OF THE CURRENT LINE) TO THE GIVEN IDENTIFIER.  ╘HE COLON IS
  531. USED WITH THIS DIRECTIVE TO MAKE IT EASY AND EFFICIENT TO PARSE, AND TO MAKE
  532. IT EASY FOR A HUMAN TO SEE THAT A LABEL IS BEING DEFINED.  ═ANY OTHER
  533. ASSEMBLERS FOLLOW THIS DIRECTIVE WITH JUST WHITESPACE AND RELY ON OTHER
  534. TRICKS, LIKE PUTTING AN UGLY DOT BEFORE EACH DIRECTIVE, TO BAIL THEM OUT.
  535. ╞OR MAXIMUM COMPATIBILITY, YOU CAN ALSO LEAVE OUT THE COLON FOLLOWING A
  536. LABEL DEFINITION AND THE ASSEMBLER WILL FIGURE OUT WHAT YOU MEAN (THOUGH A
  537. LITTLE LESS EFFICIENTLY).
  538.  
  539. ╘HE THIRD AND FOURTH SET RELATIVE REFERENCE POINTS.  ╘HEY ARE EQUIVALENT TO
  540. "REL_LABEL = *", WHERE "REL_LABEL" IS A SPECIALLY GENERATED INTERNAL
  541. IDENTIFIER OF THE FORM "╠+123C" MENTIONED IN THE EXPRESSION SECTION.  ╘HE
  542. LABELS DEFINED BY THESE DIRECTIVES SHOW UP IN THE SYMBOL TABLE DUMP, IF YOU
  543. ASK FOR ONE ON THE COMMAND LINE.  ╘HESE ARE ALSO PREFIX DIRECTIVES, SO IF
  544. YOU WANTED TO SET A FORWARD AND A BACKWARD REFERENCE TO THE SAME ADDRESS,
  545. THEN YOU WOULD DO SOMETHING LIKE:
  546.  
  547. +- LDA #1
  548.  
  549. ╔N FACT, YOU COULD PUT AS MANY OR THESE DIRECTIVES ON THE FRONT OF A LINE AS
  550. YOU WANT, THOUGH MORE THAN ONE OF EACH WILL BE OF LITTLE USE.  ╞OR SOURCE
  551. COMPATIBILITY WITH THE ┬UDDY ASSEMBLER, THE ┴├┼ ASSEMBLER WILL ALSO ACCEPT A
  552. LEADING "/" ON A LINE AS BEING EQUIVALENT TO "+-".  ╬OTE THAT BACKWARD
  553. RELATIVE LABELS WILL ALWAYS BE DEFINED AT THE POINT THAT THEY ARE REFERENCED
  554. AND FORWARD RELATIVE LABELS WILL ALWAYS BE UNDEFINED (UNRESOLVED) WHEN THEY
  555. ARE REFERENCED.  ╔F AT THE END OF YOUR ASSEMBLY JOB THE ASSEMBLER COMPLAINS
  556. OF AN UNRESOLVED REFERENCE INVOLVING A LABEL OF THE FORM "╠+123C", THEN YOU
  557. REFER TO A FORWARD-RELATIVE POINT THAT YOU DON'T SET, AND IF THE LABEL IS OF
  558. THE FORM "╠-4000000000C", THEN YOU REFER TO A BACKWARD RELATIVE POINT THAT
  559. YOU DON'T DEFINE.
  560.  
  561. 6.3. ╧╥╔╟╔╬ ─╔╥┼├╘╔╓┼
  562.  
  563. .ORG ADDRESS_EXPRESSION      ;SET THE ORIGIN OF THE ASSEMBLY
  564.  
  565. ╘HIS DIRECTIVE WILL SET THE CODE ORIGIN TO THE GIVEN EXPRESSION.  ╘HE
  566. EXPRESSION ═╒╙╘ BE RESOLVED AT THE POINT WHERE IT APPEARS, SINCE IT WOULD BE
  567. VERY DIFFICULT TO FILL IN THE TYPE OF "HOLE" THIS WOULD LEAVE BEHIND (THOUGH
  568. NOT IMPOSSIBLE, HMMM...).  ╘HE ORIGIN MUST BE SET BEFORE ANY PROCESSOR
  569. INSTRUCTION OR ASSEMBLER DIRECTIVE THAT GENERATES MEMORY VALUES OR REFERS TO
  570. THE CURRENT ADDRESS IS ENCOUNTERED, AND THE CODE ORIGIN CAN ONLY BE SET
  571. ONCE.  ╘HIS RESULTS IN A CONTIGUOUS CODE REGION, WHICH IS WHAT ┴├┼ AND THE
  572. ├OMMODORE ╦ERNAL REQUIRE.
  573.  
  574. 6.4. ─┼╞╔╬┼-┬┘╘┼╙ ─╔╥┼├╘╔╓┼╙
  575.  
  576. .BYTE EXP1, EXP2, ..., EXP╬   ;PUT BYTE VALUES INTO MEMORY
  577. .WORD EXP1, EXP2, ..., EXP╬   ;PUT WORD VALUES INTO MEMORY
  578. .TRIPLE EXP1, EXP2, ..., EXP╬ ;PUT "TRIPLE" (3-BYTE) VALUES INTO MEMORY, LO->HI
  579. .LONG EXP1, EXP2, ..., EXP╬   ;PUT "LONG" (4-BYTE) VALUES INTO MEMORY, LO->HI
  580.  
  581. ╘HESE DIRECTIVES ALL PUT BYTE VALUES INTO CODE MEMORY, AT THE CURRENT
  582. ADDRESS.  ╘HE ONLY DIFFERENCE BETWEEN THE FOUR OF THEM IS THE SIZE OF DATA
  583. VALUES THEY PUT INTO MEMORY: BYTES (8 BITS), WORDS (16 BITS), TRIPLES (24
  584. BITS), AND LONGS (32 BITS).  ╘HE CODE ADDRESS IS INCREMENTED BY THE
  585. APPROPRIATE NUMBER OF BYTES BETWEEN PUTTING EACH VALUE INTO MEMORY.  ┴NY
  586. NUMBER OF VALUES CAN BE SPECIFIED BY SEPARATING THEM BY COMMAS.  ┴LL
  587. EXPRESSIONS ARE EVALUATED IN FULL 32 BITS, BUT MUST FIT INTO THE SIZE FOR
  588. THE DIRECTIVE.  ╘HE EXPRESSIONS DON'T HAVE TO BE RESOLVED AT THE TIME THEY
  589. APPEAR.
  590.  
  591. ╘HESE DIRECTIVES CAN ALSO BE GIVEN STRINGS FOR ARGUMENTS, WHICH MEANS THAT
  592. EACH CHARACTER OF THE STRING WILL BE STORED AS ONE BYTE/WORD/ETC. IN MEMORY,
  593. FOR EXAMPLE:
  594.  
  595. .BYTE 123, ABC+XYZ+%1101-"A"+$1, "HELLO", 0, "YO!", "KEEP ON HACKIN'\0"
  596.  
  597. ╘HESE DIRECTIVES USED TO BE NAMED "DB", "DW", "DT", AND "DW", BUT ╔ CHANGED
  598. THEM TO BE MORE CONSISTENT WITH MOST OTHER 6502 ASSEMBLERS OUT THERE.
  599.  
  600. 6.5. ┬╒╞ ─╔╥┼├╘╔╓┼
  601.  
  602. .BUF SIZE_EXPRESSION       ;RESERVE "SIZE" BYTES OF SPACE, FILLED WITH ZEROES
  603.  
  604. ╘HIS DIRECTIVE RESERVES THE GIVEN NUMBER OF BYTES OF SPACE FROM THE CURRENT
  605. CODE ADDRESS AND FILLS THEM WITH ZEROES.  ╘HE EXPRESSION MUST BE RESOLVED,
  606. AND CAN BE ANY VALUE FROM 0 UP TO 65535 (OR THE NUMBER OF BYTES REMAINING
  607. UNTIL THE CODE ADDRESS OVERFLOWS THE 64╦ CODE SPACE LIMIT).
  608.  
  609. 6.6. ╔╬├╠╒─┼ ─╔╥┼├╘╔╓┼
  610.  
  611. .INCLUDE "FILENAME"       ;INCLUDE THE NAMED SOURCE FILE AT THE CURRENT POINT
  612.  
  613. ╘HIS DIRECTIVE WILL INCLUDE THE NAMED SOURCE FILE AT THE CURRENT POINT IN
  614. THE CURRENT SOURCE FILE, AS IF YOU HAD TYPED THE CONTENTS OF THE NAMED
  615. FILE WERE ACTUALLY TYPED AT THE CURRENT POINT.  ╔NPUT IS READ FROM THE
  616. INCLUDE FILE UNTIL IT HITS ┼╧╞, AND THEN INPUT IS RESUMED FROM THE CURRENT
  617. FILE IMMEDIATELY AFTER THE INCLUDE STATEMENT.  ╘HE FILENAME MUST BE IN
  618. THE FORM OF A STRING LITERAL AND IN THE ┴├┼ SYNTAX.
  619.  
  620. ╬ORMALLY, THIS FEATURE IS USED TO INCLUDE STANDARD HEADER FILES INTO AN
  621. APPLICATION, SUCH AS THE "ACEHEAD.S" FILE, BUT IT CAN ALSO BE USE TO
  622. MODULARIZE AN APPLICATION INTO A NUMBER OF DIFFERENT FUNCTIONAL MODULES.
  623.  
  624. ╔NCLUDE FILES MAY BE NESTED ARBITRARILY DEEP (INCLUDED FILES MAY INCLUDE
  625. OTHER FILES, AND SO ON) IN THE ASSEMBLER, BUT THE ┴├┼ ENVIRONMENT PUTS
  626. LIMITATIONS ON HOW MANY FILES CAN BE OPENED AT ONE TIME (ALTHOUGH, YOU
  627. SHOULD NEVER NEED TO GO MORE THAN A COUPLE OF LEVELS DEEP).  ╘HE ASSEMBLER
  628. DOESN'T CHECK FOR RECURSIVE INCLUDE FILES (ALTHOUGH IT COULD), BUT YOU WILL
  629. GET AN ERROR ANYWAY FROM ┴├┼ SINCE YOU WILL EXCEED THE NUMBER OF ALLOWED
  630. FILES TO HAVE OPENED.
  631.  
  632. ┼RROR REPORTING IS ALSO REPORTED CORRECTLY IN THE CASE THAT AN ERROR IS
  633. DETECTED IN THE CURRENT SOURCE FILE BECAUSE OF A REFERENCE IN A DIFFERENT
  634. FILE (BOTH FILES WILL BE NAMED).
  635.  
  636. 6.7. ╨┴╥╙╔╬╟ ┴╬─ ├╧═╨┴╘╔┬╔╠╔╘┘
  637.  
  638. ┬ECAUSE OF THE WAY THAT THE ASSEMBLER PARSES THE SOURCE CODE (IT USES A
  639. ONE-CHARACTER-PEEK-AHEAD AD-HOC PARSER), YOU CAN DEFINE LABELS THAT ARE ALSO
  640. DIRECTIVE NAMES OR PROCESSOR-INSTRUCTION NAMES (IF YOU USE THE COLON
  641. NOTATION).  ╘HIS IS NOT A RECOMMENDED PRACTICE, SINCE YOU CAN END UP WITH
  642. LINES THAT LOOK LIKE:
  643.  
  644. X: LDA: LDA LDA,X
  645.  
  646. ╘HE PARSER WILL KNOW WHAT TO DO, BUT MOST HUMANS WON'T.  ┴LSO, BECAUSE OF
  647. THE TOKENIZER, CAN PUT ARBITRARY SPACING BETWEEN TOKENS, EXCEPT BETWEEN
  648. TOKENS THAT WOULD OTHERWISE MERGE TOGETHER (LIKE TWO ADJACENT IDENTIFIERS OR
  649. DECIMAL NUMBERS).
  650.  
  651. ╞OR COMPATIBILITY, THE FOLLOWING DIRECTIVES ARE ALSO INCLUDE AND ARE USED
  652. AS ALIASES FOR ┴├┼-ASSEMBLER DIRECTIVES.
  653.  
  654. ┴╠╔┴╙   ┴├┼-AS     ─┼╙├╥╔╨╘╔╧╬
  655. -----   ------     -----------
  656. .ASC    .BYTE      WORKS SINCE THE BYTE DIRECTIVE ACCEPTS STRINGS
  657. .BYT    .BYTE      EQUIVALENT
  658. .SEQ    .INCLUDE   EQUIVALENT; THE FILENAME MUST BE A LITERAL STRING
  659. .OBJ    ;          ALL TOKENS FOLLOWING THIS ARE IGNORED ╒╬╘╔╠ THE ├╥
  660. .END    <EOF>      END THE ASSEMBLY OF THE CURRENT FILE
  661. ------------------------------------------------------------------------------
  662. 7. ┼╥╥╧╥ ╚┴╬─╠╔╬╟
  663.  
  664. ╫HEN AN ERROR IS DETECTED, THE ASSEMBLER WILL STOP THE WHOLE ASSEMBLY JOB
  665. AND PRINT OUT ONE ERROR MESSAGE (TO THE STDERR FILE STREAM).  ╚ERE ARE TWO
  666. EXAMPLES OF ERROR MESSAGES:
  667.  
  668. ERR ("K:":2:0) ╓ALUE IS TOO LARGE OR NEGATIVE
  669.  
  670. ERR ("K:":3:0), REF("K:":2:0) ╓ALUE IS TOO LARGE OR NEGATIVE
  671.  
  672. ╔N BOTH ERROR MESSAGES, THE STUFF INSIDE OF THE PARENTHESES IS THE FILENAME
  673. OF THE SOURCE FILE (THE KEYBOARD HERE), THE SOURCE LINE WHERE THE ERROR WAS
  674. DETECTED, AND THE COLUMN NUMBER WHERE THE ERROR WAS DETECTED.  ├URRENTLY,
  675. THE COLUMN NUMBER IS NOT IMPLEMENTED SO IT IS ALWAYS ZERO.  ╫HEN IT IS
  676. IMPLEMENTED, THE COLUMN NUMBERS WILL START FROM 1, LIKE IN THE ┌ED TEXT
  677. EDITOR, AND IT WILL POINT TO THE FIRST CHARACTER OF THE TOKEN WHERE THE
  678. ERROR WAS DISCOVERED.
  679.  
  680. ╔N THE FIRST EXAMPLE, THE ERROR OCCURRED BECAUSE THE EXPRESSION WAS RESOLVED
  681. AND THE VALUE WAS FOUND TO BE TOO LARGE FOR WHATEVER OPERATION WAS
  682. ATTEMPTED.  ╔N THE SECOND EXAMPLE, AN EXPRESSION WAS USED BUT UNRESOLVED ON
  683. LINE 2 OF THE SOURCE FILE, AND WHEN ITS UNRESOLVED IDENTIFIER(S) WAS FINALLY
  684. FILLED IN IN LINE 3 OF THE SOURCE, THE "HOLE" TO BE FILLED IN WAS FOUND TO
  685. BE TOO SMALL FOR THE VALUE, SO AN ERROR RESULTED.  ╘HIS IS WHAT THE "REF"
  686. FILE POSITION MEANS.  ╞ILENAMES ARE INCLUDED IN ERROR MESSAGES BECAUSE IN
  687. THE FUTURE, IT WILL BE POSSIBLE TO HAVE ERRORS CROP UP IN INCLUDED FILES AND
  688. ELSEWHERE.
  689.  
  690. ╚ERE IS THE ENTIRE LIST OF POSSIBLE ERROR MESSAGES:
  691.  
  692. ╬╒═  ═┼┴╬╔╬╟
  693. ---  -------
  694. 01.  "┴N IDENTIFIER TOKEN EXCEEDS 240 CHARS IN LENGTH"
  695. 02.  "┴ STRING LITERAL EXCEEDS 240 CHARS IN LENGTH"
  696. 03.  "╥AN INTO A ├╥ BEFORE END OF STRING LITERAL"
  697. 04.  "╔NVALID NUMERIC LITERAL"
  698. 05.  "╬UMERIC LITERAL VALUE OVERFLOWS 32-BITS"
  699. 06.  "╙YNTAX ERROR"
  700. 07.  "┴TTEMPT TO PERFORM NUMERIC OPERATORS ON A STRING"
  701. 08.  "┼XPRESSION HAS MORE THAN 17 OPERANDS"
  702. 09.  "╥AN OUT OF MEMORY DURING COMPILATION PROCESS"
  703. 10.  "┴TTEMPT TO REDEFINE A SYMBOL"
  704. 11.  "┴TTEMPT TO ASSEMBLE CODE WITH CODE ORIGIN NOT SET"
  705. 12.  "╔NTERNAL ERROR: ┘OU SHOULD NEVER SEE THIS ERROR!"
  706. 13.  "╬ON-NUMERIC SYMBOL IN A NUMERIC EXPRESSION"
  707. 14.  "┼XPECTING AN OPERATOR"
  708. 15.  "┼XPECTING AN OPERAND"
  709. 16.  "┼XPECTING A COMMAND"
  710. 17.  "╓ALUE IS TOO LARGE OR NEGATIVE"
  711. 18.  "┬RANCH OUT OF RANGE"
  712. 19.  "╞EATURE IS NOT (YET) IMPLEMENTED"
  713. 20.  "╔NSTRUCTION DOES NOT SUPPORT GIVEN ADDRESS MODE"
  714. 21.  "┴DDRESS WRAPED AROUND 64╦ CODE ADDRESS SPACE"
  715. 22.  "┼RROR TRYING TO WRITE OUTPUT OBJECT FILE"
  716. 23.  "─IRECTIVE REQUIRES RESOLVED EXPRESSION"
  717. 24.  "├ODE ORIGIN ALREADY SET; YOU CAN'T SET IT TWICE"
  718. 25.  "╒NRESOLVED SYMBOL: "
  719. 26.  "┼XPECTING A STRING-LITERAL FILENAME"
  720.  
  721. ┴ "╙YNTAX ERROR" (#06) WILL BE REPORTED WHENEVER A TOKEN OTHER THAN ONE THAT
  722. WAS EXPECTED IS FOUND (EXCEPT IN THE CASES OF THE OTHER '┼XPECTING'
  723. MESSAGES).  "╥AN OUT OF MEMORY" (#09) MAY TURN UP OFTEN ON AN UNEXPANDED
  724. 64.  "┼XPECTING COMMAND" (#16) MEANS THAT THE ASSEMBLER WAS EXPECTING EITHER
  725. A PROCESSOR INSTRUCTION OR DIRECTIVE BUT FOUND SOMETHING ELSE INSTEAD.  "╬OT
  726. IMPLEMENTED" (#19) MEANS THAT YOU'VE TRIED TO USE A DIRECTIVE THAT ISN'T
  727. IMPLEMENTED YET.  "╒NRESOLVED SYMBOL" (#25) WILL BE PRINTED WITH A RANDOMLY
  728. CHOSEN UNRESOLVED SYMBOL, WITH THE LAST PLACE IN THE SOURCE CODE WHERE IT
  729. WAS REFERENCED.
  730.  
  731. ╘HERE ARE TWO MAIN REASONS BEHIND THE IDEA OF STOPPING AT THE FIRST ERROR
  732. ENCOUNTERED: SIMPLICITY AND INTEROPERABILITY.  ╫HEN ┌┼─ IS IMPLEMENTED FOR
  733. ┴├┼, IT WILL HAVE A FEATURE THAT WILL ALLOW IT TO INVOKE THE ASSEMBLER (AS A
  734. SUB-PROCESS) AND HAVE THE ASSEMBLER RETURN AN ERROR LOCATION AND MESSAGE TO
  735. ┌┼─, WHICH WILL DISPLAY THE ERROR MESSAGE AND POSITION THE CURSOR TO THE
  736. ERROR LOCATION (IF THE SOURCE FILE IS LOADED).
  737.  
  738. ╫HILE ON THE SUBJECT OF MESSAGES COMING OUT OF THE ASSEMBLER, HERE IS AN
  739. EXAMPLE OF THE FORMAT OF THE SYMBOL TABLE DUMP THAT YOU CAN ASK FOR ON THE
  740. COMMAND LINE.  ╧NE LINE IS PRINTED FOR EACH IDENTIFIER.  ╘HE "HASH" VALUE IS
  741. THE BUCKET IN THE HASH TABLE CHOSEN FOR THE IDENTIFIER.  ╘HIS MAY NOT HAVE A
  742. WHOLE LOT OF MEANING FOR A USER, BUT A GOOD DISTRIBUTION OF THESE HASH
  743. BUCKETS IN THE SYMBOL TABLE IS A GOOD THING.  ╬EXT IS THE 32-BIT "HEXVALUE"
  744. OF THE LABEL FOLLOWED BY THE VALUE IN "DECIMAL".  ╘HEN COMES THE TYPE.  ┴
  745. TYPE OF "V" MEANS VALUE, "A" IN-CODE-RANGE ADDRESS, "L" MEANS AN ADDRESS
  746. LOW-BYTE, "H" MEANS AN ADDRESS HIGH-BYTE, AND "G" MEANS A 'GARBAGE' TYPE.
  747. ╘HEN COMES THE NAME OF THE IDENTIFIER.  ╔T COMES LAST TO GIVE LOTS OF SPACE
  748. TO PRINT IT.  ╔F AN IDENTIFIER IS TEN OR FEWER CHARACTERS LONG, ITS
  749. SYMBOL-TABLE-DUMP LINE WILL FIT ON A 40-COLUMN SCREEN.  ┴T THE BOTTOM, THE
  750. NUMBER OF SYMBOLS IS PRINTED.  ╘HIS TABLE IS DIRECTED TO THE STDOUT FILE
  751. STREAM, SO YOU CAN REDIRECT IT TO A FILE IN ORDER TO SAVE IT.
  752.  
  753. ╚┴╙╚  ╚┼╪╓┴╠╒┼    ─┼├╔═┴╠  ╘  ╬┴═┼
  754. ----  -------- ----------  -  -----
  755.    8  00000F06       3846  V  ACE┴RGV
  756.  469  00007008      28680  A  MAIN
  757. --
  758. ╬UMBER OF SYMBOLS: 2
  759. ------------------------------------------------------------------------------
  760. 8. ╔═╨╠┼═┼╬╘┴╘╔╧╬
  761.  
  762. ╔N EACH OF THE WAYS IN WHICH IT IS HEAVY-WEIGHT AND SLOWED-DOWN COMPARED TO
  763. OTHER ASSEMBLERS, IT IS ALSO MORE POWERFUL AND MORE FLEXIBLE.
  764.  
  765. - ╔T USES FAR MEMORY FOR STORING SYMBOLS, SO THERE IS NO STATIC OR
  766.   ARBITRARILY SMALL LIMIT ON THE NUMBER OF SYMBOLS.  ═ACRO SIZES WILL ALSO
  767.   BE LIMITED BY ONLY THE AMOUNT OF MEMORY AVAILABLE, AS WELL AS THE "HOLE
  768.   TABLE".
  769.  
  770. - ╔T HAS TO MAINTAIN A "HOLE TABLE" BECAUSE OF ITS STRUCTURE, BUT THIS MEANS
  771.   THAT YOU CAN DEFINE LABELS IN TERMS OF OTHER UNRESOLVED LABELS, THAT YOU
  772.   WILL NEVER GET A "SYNC ERROR" BECAUSE OF INCORRECT ASSUMPTIONS MADE (AND
  773.   NOT RECORDED) ABOUT UNRESOLVED LABELS, AND THAT MODULAR ASSEMBLY CAN BE
  774.   IMPLEMENTED WITHOUT TOO MUCH FURTHER EFFORT (I.E., ".O" OR ".OBJ" FILES),
  775.   SINCE AN UNRESOLVED EXTERNAL REFERENCE HANDLING MECHANISM IS ALREADY
  776.   IMPLEMENTED.
  777.  
  778. - ╘HE ASSEMBLER KEEPS TRACK OF THE "TYPES" OF LABELS WHICH MAKES IT POSSIBLE
  779.   TO PROVIDE CODE RELOCATION INFORMATION THAT WILL BE NEEDED BY MODULAR
  780.   ASSEMBLY AND BY FUTURE MULTITASKING OPERATING SYSTEMS.
  781.  
  782. - ┬ECAUSE A "HOLE TABLE" APPROACH IS USED, THE RAW OBJECT CODE MUST BE
  783.   STORED INTERNALLY UNTIL THE ASSEMBLY IS COMPLETE AND THEN IT CAN BE
  784.   WRITTEN OUT TO A FILE, BUT THIS ALSO MEANS THAT HEADER INFORMATION CAN BE
  785.   PROVIDED IN AN OUTPUT FILE SINCE ALL ASSEMBLY RESULTS WILL BE KNOWN BEFORE
  786.   ANY OUTPUT IS WRITTEN.
  787.  
  788. - ╔ TOOK THE EASY WAY OUT FOR HANDLING ERRORS; WHEN AN ERROR IS DETECTED, AN
  789.   ERROR MESSAGE IS GENERATED AND PRINTED AND THE ASSEMBLER ╙╘╧╨S.  ┬UT THE
  790.   EXIT MECHANISM PROVIDED BY ┴├┼ MAKES IT POSSIBLE TO INTEGRATE THE
  791.   ASSEMBLER WITH OTHER PROGRAMS, LIKE A TEXT EDITOR, TO MOVE THE TEXT EDITOR
  792.   CURSOR TO THE LINE AND COLUMN CONTAINING THE ERROR AND DISPLAY A MESSAGE
  793.   IN THE TEXT EDITOR.
  794.  
  795. ╘HERE ARE TWO SPEED ADVANTAGES THAT THIS ASSEMBLER HAS OVER (SOME?) OTHERS:
  796.  
  797. - ╔T USES A 1024-ENTRY HASH TABLE OF POINTERS TO CHAINS OF LABELS, SO, FOR A
  798.   PROGRAM THAT HAS 800 OR SO SYMBOLS, EACH CAN BE ACCESSED IN SOMETHING LIKE
  799.   1.3 TRIES.  ╞OR ╬ TOTAL SYMBOLS, THE REQUIRED NUMBER OF REFERENCES IS
  800.   APPROXIMATELY ═┴╪( ╬/1024, 1 ).
  801.  
  802. - ╔T IS ONE-PASS, SO IT ONLY HAS TO GO THROUGH THE OVERHEAD OF READING THE
  803.   SOURCE FILE ONCE.  ─EPENDING ON THE TYPE OF DEVICE THE FILE IS STORED ON,
  804.   THIS MAY GIVE A CONSIDERABLE SAVINGS.  ╘HIS ALSO MAKES IT POSSIBLE TO
  805.   "PIPE" THE OUTPUT OF ANOTHER PROGRAM INTO THE ASSEMBLER, WITHOUT ANY
  806.   "REWIND" PROBLEMS.
  807.  
  808. ╚ERE ARE SOME (OLD) PERFORMACE FIGURES, COMPARED TO THE ┬UDDY ASSEMBLER FOR
  809. THE 128.  ┴LL TEST CASES WERE RUN ON A ├128 IN 2-═╚Z MODE WITH A ╥┴═╠INK,
  810. ╥┼╒, AND 1571 AVAILABLE.
  811.  
  812. ┴╙╙┼═┬   ╘╔═┼(SEC)   ╞╔╠┼ ─┼╓╔├┼   ╞┴╥ ╙╘╧╥┴╟┼
  813. ------   ---------   -----------   -----------
  814. ┬UDDY         45.5   ╥┴═╠INK       N/A
  815. ┴├┼-AS        61.5   ╥┴═╠INK       ╥┼╒
  816. ┴├┼-AS        49.5   ┴├┼ RAMDISK   ╥┼╒
  817. ┴├┼-AS        75.6   ╥┴═╠INK       ╥┴═0+╥┴═1
  818. ┴├┼-AS       150.5   1571          ╥┴═0+╥┴═1
  819. ┬UDDY        240.0   1571          N/A
  820.  
  821. ╨ART OF THE ASSEMBLY JOB WAS LOADED INTO MEMORY FOR THE ┬UDDY ASSEMBLER, BUT
  822. THE LOAD TIME IS INCLUDED IN THE FIGURE.  ┴S YOU CAN SEE, BUDDY PERFORMS
  823. FASTER WITH A FAST FILE DEVICE AND SLOWER WITH A SLOW FILE DEVICE (BECAUSE
  824. IT REQUIRES TWO PASSES).  ╔ HAVE A COUPLE OF TRICKS UP MY SLEEVE TO IMPROVE
  825. THE ┴├┼ ASSEMBLER'S PERFORMANCE.
  826.  
  827. ╚ERE ARE A FEW DATA STRUCTURES FOR YOUR ENJOYMENT.
  828.  
  829. ╔DENTIFIER DESCRIPTOR:
  830.  
  831. ╧╞╞   ╙╔┌   ─┼╙├╥╔╨╘╔╧╬
  832. ---   ---   ------------
  833.   0     4   NEXT LINK IN HASH TABLE BUCKET
  834.   4     4   VALUE OF SYMBOL, POINTER TO REFERENCE LIST, OR PTR TO MACRO DEFN
  835.   8     1   OFFSET OF REFERENCE IN EXPRESSION OF REFERENCE LIST
  836.   9     1   TYPE: $00=VALUE, $01=ADDRESS, $02=LOW-BYTE, $03=HIGH-BYTE,
  837.                   $04=GARBAGE, $80=UNRESOLVED, $FF=UNRESOLVED DEFINE
  838.  10     1   CLASS: $00=NORMAL, $01=PRIVATE, $80=GLOBAL (NOT USED YET)
  839.  11     1   NAME LENGTH
  840.  12     N   NULL-TERMINATED NAME STRING (1-240 CHARS)
  841. 12+N    -   ╙╔┌┼
  842.  
  843. ┼XPRESSION/╚OLE DESCRIPTOR:
  844.  
  845. ╧╞╞   ╙╔┌   ─┼╙├╥╔╨╘╔╧╬
  846. ---   ---   -----------
  847.   0     1   HOLE TYPE: $01=BYTE, $02=WORD, $03=TRIPLE, $04=LONG, $40=BRANCH,
  848.             $80=LABEL
  849.   1     1   EXPRESSION LENGTH: MAXIMUM OFFSET+1 IN BYTES
  850.   2     1   NUMBER OF UNRESOLVED REFERENCES IN EXPRESSION
  851.   3     1   SOURCE COLUMN OF REFERENCE
  852.   4     4   ADDRESS OF HOLE
  853.   8     4   SOURCE LINE OF REFERENCE
  854.  12     4   SOURCE FILE POINTER
  855.  16    14   EXPRESSION OPERAND DESCRIPTOR SLOT #1
  856.  30    14   EXPRESSION OPERAND DESCRIPTOR SLOT #2
  857.  44    14   EXPRESSION OPERAND DESCRIPTOR SLOT #3
  858.  58    14   EXPRESSION OPERAND DESCRIPTOR SLOT #4
  859.  72    14   EXPRESSION OPERAND DESCRIPTOR SLOT #5
  860.  86    14   EXPRESSION OPERAND DESCRIPTOR SLOT #6
  861. 100    14   EXPRESSION OPERAND DESCRIPTOR SLOT #7
  862. 114    14   EXPRESSION OPERAND DESCRIPTOR SLOT #8
  863. 128    14   EXPRESSION OPERAND DESCRIPTOR SLOT #9
  864. 142    14   EXPRESSION OPERAND DESCRIPTOR SLOT #10
  865. 156    14   EXPRESSION OPERAND DESCRIPTOR SLOT #11
  866. 170    14   EXPRESSION OPERAND DESCRIPTOR SLOT #12
  867. 184    14   EXPRESSION OPERAND DESCRIPTOR SLOT #13
  868. 198    14   EXPRESSION OPERAND DESCRIPTOR SLOT #14
  869. 212    14   EXPRESSION OPERAND DESCRIPTOR SLOT #15
  870. 226    14   EXPRESSION OPERAND DESCRIPTOR SLOT #16
  871. 240    14   EXPRESSION OPERAND DESCRIPTOR SLOT #17
  872. 254     -   ╙╔┌┼
  873.  
  874. ┼XPRESSION OPERAND DESCRIPTOR:
  875.  
  876. ╧╞╞   ╙╔┌   ─┼╙├╥╔╨╘╔╧╬
  877. ---   ---   -----------
  878.   0     1   DYADIC OPERATOR: "+", "-", "*", "/", "!", "&", "▄", OR "^"
  879.   1     1   TYPE OF VALUE: $00=VALUE, $01=ADDRESS, $02=LOW-BYTE, $03=HIGH-BYTE,
  880.             $04=GARBAGE TYPE, $80=UNRESOLVED IDENTIFIER
  881.   2     1   MONADIC-OPERATOR RESULT SIGN OF VALUE: $00=POSITIVE, $80=NEGATIVE
  882.   3     1   HI/LO OPERATOR COUNTS: HIGH_NYBBLE=">" COUNT, LOW_NYBBLE="<" COUNT
  883.   4     4   NUMERIC VALUE OR UNRESOLVED-IDENTIFIER POINTER
  884.   8     4   NEXT UNRESOLVED REFERENCE IN CHAIN FOR UNRESOLVED IDENTIFIER
  885.  12     1   OFFSET IN HOLE STRUCTURE OF NEXT UNRESOLVED REFERENCE (OPERAND)
  886.  13     1   RESERVED
  887.  14     -   ╙╔┌┼
  888.  
  889. ╞ILE ╔DENTIFIER:
  890.  
  891. ╧╞╞   ╙╔┌   ─┼╙├╥╔╨╘╔╧╬
  892. ---   ---   -----------
  893.   0     4   POINTER TO PREVIOUS FILE IDENTIFIER ON INCLUDE STACK
  894.   4     4   LINE NUMBER SAVE
  895.   8     4   COLUMN NUMBER SAVE
  896.  12     1   FILE TYPE: $00=REGULAR, $01=STDIN, $80=MACRO
  897.  13     1   FILE DESCRIPTOR SAVE
  898.  14     1   PREVIOUS CHARACTER SAVE
  899.  15     1   BUFFER POINTER SAVE
  900.  16     4   POINTER TO BUFFER SAVE AREA (CHAR[256])
  901.  20     4   RESERVED
  902.  24     1   LENGTH OF ENTIRE FILE-IDENTIFIER RECORD
  903.  25     N   FILENAME + '\0'
  904. 25+N    -   ╙╔┌┼
  905. ------------------------------------------------------------------------------
  906. 9. ╘╚┼ ╞╒╘╒╥┼
  907.  
  908. ╘HIS SECTION IS JUST RANDOM NOTES SINCE ╔ DON'T HAVE THE TIME RIGHT NOW TO
  909. FILL IT IN.  ╔ WILL BE IMPLEMENTING INCLUDE FILES, CONDITIONAL ASSEMBLY, AND
  910. MACRO ASSEMBLY FEATURES IN THE FUTURE.  ═ODULAR ASSEMBLY AND RELOCATABLE-
  911. CODE GENERATION ARE ALSO IN MY PLANS.
  912.  
  913. ;TODO: -IMPLEMENT STORAGE CLASSES: $00=INTERNAL, $01=REL.LABEL, $80=EXPORTED
  914. ;      -IMPLEMENT SOURCE COLUMN, MAKE LINE:COL POINT TO START OF CUR TOKEN
  915. ;      -MAKE IT SO YOU CAN USE A "\<├╥>" TO CONTINUE A LINE (MACRO)
  916. ;
  917. ; USAGE: AS [-HELP] [-S] [-D] [-B] [-R] [-L] [-A ADDR] [FILE ...] [-O FILENAME]
  918. ;
  919. ;     -HELP : PRODUCE THIS INFORMATION, DON'T RUN
  920. ;        -S : PRODUCE SYMBOL TABLE DUMP AT END
  921. ;        -D : PROVIDE DEBUGGING INFORMATION (LOTS)
  922. ;        -B : PRODUCE BINARY MODULE AT END (DEFAULT)
  923. ;        -R : PRODUCE RELOCATABLE MODULE RATHER THAN BINARY MODULE
  924. ;        -L : PRODUCE LINKABLE ".O" MODULE(S)
  925. ;        -A : SET GLOBAL CODE ORIGIN TO GIVEN ADDRESS
  926. ;        -O : PUT OUTPUT INTO GIVEN FILENAME
  927. ;
  928. ;     ╔F -L OPTION IS NOT USED, ALL FILES, INCLUDING SOURCE AND OBJECT MODULES,
  929. ; WILL BE ASSEMBLED TOGETHER.  ╘HE OUTPUT MODULE NAME WILL BE THE BASE NAME OF
  930. ; THE FIRST FILE GIVEN IF IT HAS A ".S" OR ".O" EXTENSION, "A.OUT" IF THE FIRST
  931. ; FILE HAS NONE OF THESE EXTENSIONS, OR WILL BE THE FILENAME GIVEN BY THE -O
  932. ; OPTION IF USED.
  933. ;     ╔F THE -L OPTION IS USED, THEN EACH GIVEN SOURCE MODULE WILL BE
  934. ; ASSEMBLED INDEPENDENTLY INTO ITS OWN ".O" MODULE.  ╧BJECT MODULES WILL BE
  935. ; IGNORED.
  936. ;     ╘HE GLOBAL ORIGIN WILL BE EITHER THAT GIVEN BY THE -A OPTION (IF IT IS
  937. ; USED) OR BY THE LOCAL ORIGIN OF THE FIRST SOURCE/OBJECT MODULE.  ┼ACH
  938. ; SOURCE MODULE THAT GENERATES CODE MUST HAVE A LOCAL CODE ORIGIN.
  939.  
  940. ═ORE ─IRECTIVES:
  941.  
  942. IF <EXPRESSION> <RELOP> <EXPRESSION>
  943. ELSIF <EXPRESSION> <RELOP> <EXPRESSION>
  944. ELSE
  945. ENDIF
  946. MACRO MACRONAME
  947. ENDMACRO
  948. EXPORT LABEL1, LABEL2, ..., LABEL╬
  949. BSS SIZE_EXPRESSION
  950.  
  951. MACRO BLT ;?1=ADDR
  952.    BCC ?1
  953. ENDMACRO
  954.  
  955. MACRO ADD ;?1=OPERAND
  956.    CLC
  957.    ADC ?1
  958. ENDMACRO
  959.  
  960. MACRO LDW ;?1=DEST, ?2=SOURCE
  961.  IF ?# != 2
  962.    ERROR "THE LDW MACRO INSTANCE DOESN'T HAVE TWO ARGUMENTS"
  963.  ENDIF
  964.  IF @1 = #
  965.    ARGSHIFT 2 0
  966.    LDA #<?2
  967.    STA ?1+0
  968.    LDA #>?2
  969.    STA ?1+1
  970.  ELSE
  971.    LDA ?2+0
  972.    STA ?1+0
  973.    LDA ?2+1
  974.    STA ?1+1
  975.  ENDIF
  976. ENDMACRO
  977. ------------------------------------------------------------------------------
  978. ╙O, THERE IS FINALLY A POWERFUL AND CONVENIENT ASSEMBLER UNIVERSALLY
  979. AVAILABLE FOR BOTH THE 64 AND 128... FOR FREE.  ╘HE SOURCE CODE FOR THE
  980. ASSEMBLER (WHICH CAN BE ASSEMBLED BY THE ASSEMBLER, OF COURSE) IS ALSO
  981. AVAILABLE FOR FREE.  ╘HERE ARE A FEW MORE FEATURES THAT NEED TO BE
  982. IMPLEMENTED, BUT ╔ KNOW EXACTLY HOW TO IMPLEMENT THEM.
  983.  
  984. ╦EEP ON ╚ACKIN'!
  985.  
  986. -├RAIG ┬RUCE
  987. CSBRUCE@CCNGA.UWATERLOO.CA
  988. "╟IVE THEM APPLICATIONS AND THEY WILL ONLY WANT MORE; GIVE THEM DEVELOPMENT
  989.  TOOLS AND THEY WILL GIVE YOU APPLICATIONS, AND MORE."
  990. ------------------------------------------------------------------------┼╬─---
  991.